home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kresolver.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  29.7 KB  |  946 lines

  1. /*  -*- mode: C++; coding: utf-8; -*-
  2.  *  Copyright (C) 2003,2005 Thiago Macieira <thiago.macieira@kdemail.net>
  3.  *
  4.  *
  5.  *  Permission is hereby granted, free of charge, to any person obtaining
  6.  *  a copy of this software and associated documentation files (the
  7.  *  "Software"), to deal in the Software without restriction, including
  8.  *  without limitation the rights to use, copy, modify, merge, publish,
  9.  *  distribute, sublicense, and/or sell copies of the Software, and to
  10.  *  permit persons to whom the Software is furnished to do so, subject to
  11.  *  the following conditions:
  12.  *
  13.  *  The above copyright notice and this permission notice shall be included 
  14.  *  in all copies or substantial portions of the Software.
  15.  *
  16.  *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  17.  *  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  18.  *  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  19.  *  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  20.  *  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  21.  *  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  22.  *  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  23.  */
  24.  
  25. #ifndef KRESOLVER_H
  26. #define KRESOLVER_H
  27.  
  28. //////////////////
  29. // Needed includes
  30. #include <qvaluelist.h>
  31. #include <qobject.h>
  32. #include "ksocketaddress.h"
  33.  
  34.  
  35. ////////////////////////
  36. // Forward declarations
  37. struct sockaddr;
  38. class QString;
  39. class QCString;
  40. class QStrList;
  41.  
  42. //////////////////
  43. // Our definitions
  44.  
  45. namespace KNetwork {
  46.  
  47.   namespace Internal { class KResolverManager; }
  48.  
  49. class KResolverEntryPrivate;
  50. /** @class KResolverEntry kresolver.h kresolver.h
  51.  *  @brief One resolution entry.
  52.  *
  53.  * This class is one element in the resolution results list.
  54.  * It contains the socket address for connecting, as well as
  55.  * a bit more of information: the socket type, address family
  56.  * and protocol numbers.
  57.  *
  58.  * This class contains all the information required for creating,
  59.  * binding and connecting a socket.
  60.  *
  61.  * KResolverEntry objects implicitly share data, so copying them
  62.  * is quite efficient.
  63.  *
  64.  * @author Thiago Macieira <thiago.macieira@kdemail.net>
  65.  */
  66. class KDECORE_EXPORT KResolverEntry
  67. {
  68. public:
  69.   /**
  70.    * Default constructor
  71.    *
  72.    */
  73.   KResolverEntry();
  74.  
  75.   /**
  76.    * Constructs a new KResolverEntry from a KSocketAddress
  77.    * and other data.
  78.    *
  79.    * The KSocketAddress @p addr parameter will be deep-copied.
  80.    *
  81.    * @param addr    the address that was resolved
  82.    * @param socktype    the socket type of the resolved address
  83.    * @param protocol    the protocol of the resolved address
  84.    * @param canonName    the canonical name of the resolved hostname
  85.    * @param encodedName    the ASCII-compatible encoding of the hostname
  86.    */
  87.   KResolverEntry(const KSocketAddress& addr, int socktype, int protocol,
  88.         const QString& canonName = QString::null,
  89.         const QCString& encodedName = QCString());
  90.  
  91.   /**
  92.    * Constructs a new KResolverEntry from raw forms of
  93.    * socket addresses and other data.
  94.    *
  95.    * This constructor instead creates an internal KSocketAddress object.
  96.    *
  97.    * @param sa        the sockaddr structure containing the raw address
  98.    * @param salen    the length of the sockaddr structure
  99.    * @param socktype    the socket type of the resolved address
  100.    * @param protocol    the protocol of the resolved address
  101.    * @param canonName    the canonical name of the resolved hostname
  102.    * @param encodedName    the ASCII-compatible encoding of the hostname
  103.    */
  104.   KResolverEntry(const struct sockaddr *sa, Q_UINT16 salen, int socktype,
  105.         int protocol, const QString& canonName = QString::null,
  106.         const QCString& encodedName = QCString());
  107.  
  108.   /**
  109.    * Copy constructor.
  110.    *
  111.    * This constructor performs a shallow-copy of the other object.
  112.    */
  113.   KResolverEntry(const KResolverEntry &other);
  114.  
  115.   /**
  116.    * Destructor.
  117.    *
  118.    * The destructor frees associated resources with this object. It does
  119.    * not destroy shared data.
  120.    */
  121.   ~KResolverEntry();
  122.  
  123.   /**
  124.    * Retrieves the socket address associated with this entry.
  125.    */
  126.   KSocketAddress address() const;
  127.  
  128.   /**
  129.    * Retrieves the length of the socket address structure.
  130.    */
  131.   Q_UINT16 length() const;
  132.  
  133.   /**
  134.    * Retrieves the family associated with this socket address.
  135.    */
  136.   int family() const;
  137.  
  138.   /**
  139.    * Retrieves the canonical name associated with this entry, if there is any.
  140.    * If the canonical name was not found, this function returns QString::null.
  141.    */
  142.   QString canonicalName() const;
  143.  
  144.   /**
  145.    * Retrieves the encoded domain name associated with this entry, if there is
  146.    * any. If this domain has been resolved through DNS, this will be the
  147.    * the ACE-encoded hostname.
  148.    *
  149.    * Returns a null QCString if such information is not available.
  150.    *
  151.    * Please note that this information is NOT to be presented to the user,
  152.    * unless requested.
  153.    */
  154.   QCString encodedName() const;
  155.  
  156.   /**
  157.    * Retrieves the socket type associated with this entry.
  158.    */
  159.   int socketType() const;
  160.  
  161.   /**
  162.    * Retrieves the protocol associated with this entry.
  163.    */
  164.   int protocol() const;
  165.  
  166.   /**
  167.    * Assignment operator
  168.    *
  169.    * This function copies the contents of the other object into this one.
  170.    * Data will be shared between the two of them.
  171.    */
  172.   KResolverEntry& operator=(const KResolverEntry& other);
  173.  
  174. private:
  175.   KResolverEntryPrivate* d;
  176. };
  177.  
  178. class KResolverResultsPrivate;
  179. /**
  180.  * @class KResolverResults kresolver.h kresolver.h
  181.  * @brief Name and service resolution results.
  182.  *
  183.  * This object contains the results of a name and service resolution, as
  184.  * those performed by @ref KResolver. It is also a descendant of QValueList, so
  185.  * you may use all its member functions here to access the elements.
  186.  *
  187.  * A KResolverResults object is associated with a resolution, so, in addition
  188.  * to the resolved elements, you can also retrieve information about the 
  189.  * resolution process itself, like the nodename that was resolved or an error
  190.  * code.
  191.  *
  192.  * Note Resolver also uses KResolverResults objects to indicate failure, so
  193.  * you should test for failure.
  194.  *
  195.  * @author Thiago Macieira <thiago.macieira@kdemail.net>
  196.  */
  197. class KDECORE_EXPORT KResolverResults: public QValueList<KResolverEntry>
  198. {
  199. public:
  200.   /**
  201.    * Default constructor.
  202.    *
  203.    * Constructs an empty list.
  204.    */
  205.   KResolverResults();
  206.  
  207.   /**
  208.    * Copy constructor
  209.    *
  210.    * Creates a new object with the contents of the other one. Data will be
  211.    * shared by the two objects, like QValueList
  212.    */
  213.   KResolverResults(const KResolverResults& other);
  214.  
  215.   /**
  216.    * Destructor
  217.    *
  218.    * Destroys the object and frees associated resources.
  219.    */
  220.   virtual ~KResolverResults();
  221.  
  222.   /**
  223.    * Assignment operator
  224.    *
  225.    * Copies the contents of the other container into this one, discarding
  226.    * our current values.
  227.    */
  228.   KResolverResults& operator=(const KResolverResults& other);
  229.  
  230.   /**
  231.    * Retrieves the error code associated with this resolution. The values
  232.    * here are the same as in @ref KResolver::ErrorCodes.
  233.    */
  234.   int error() const;
  235.  
  236.   /**
  237.    * Retrieves the system error code, if any.
  238.    * @see KResolver::systemError for more information
  239.    */
  240.   int systemError() const;
  241.  
  242.   /**
  243.    * Sets the error codes
  244.    *
  245.    * @param errorcode        the error code in @ref KResolver::ErrorCodes
  246.    * @param systemerror    the system error code associated, if any
  247.    */
  248.   void setError(int errorcode, int systemerror = 0);
  249.  
  250.   /**
  251.    * The nodename to which the resolution was performed.
  252.    */
  253.   QString nodeName() const;
  254.  
  255.   /**
  256.    * The service name to which the resolution was performed.
  257.    */
  258.   QString serviceName() const;
  259.  
  260.   /**
  261.    * Sets the new nodename and service name
  262.    */
  263.   void setAddress(const QString& host, const QString& service);
  264.  
  265. protected:
  266.   virtual void virtual_hook( int id, void* data );
  267. private:
  268.   KResolverResultsPrivate* d;
  269. };
  270.  
  271. class KResolverPrivate;
  272. /**
  273.  * @class KResolver kresolver.h kresolver.h
  274.  * @brief Name and service resolution class.
  275.  *
  276.  * This class provides support for doing name-to-binary resolution
  277.  * for nodenames and service ports. You should use this class if you
  278.  * need specific resolution techniques when creating a socket or if you
  279.  * want to inspect the results before calling the socket functions.
  280.  *
  281.  * You can either create an object and set the options you want in it
  282.  * or you can simply call the static member functions, which will create
  283.  * standard Resolver objects and dispatch the resolution for you. Normally,
  284.  * the static functions will be used, except in cases where specific options
  285.  * must be set.
  286.  *
  287.  * A Resolver object defaults to the following:
  288.  * @li address family: any address family
  289.  * @li socket type: streaming socket
  290.  * @li protocol: implementation-defined. Generally, TCP
  291.  * @li host and service: unset
  292.  *
  293.  * @author Thiago Macieira <thiago.macieira@kdemail.net>
  294.  */
  295. class KDECORE_EXPORT KResolver: public QObject
  296. {
  297.   Q_OBJECT
  298.  
  299. public:
  300.  
  301.   /**
  302.    * Address family selection types
  303.    *
  304.    * These values can be OR-ed together to form a composite family selection.
  305.    *
  306.    * @li UnknownFamily: a family that is unknown to the current implementation
  307.    * @li KnownFamily: a family that is known to the implementation (the exact
  308.    *        opposite of UnknownFamily)
  309.    * @li AnyFamilies: any address family is acceptable
  310.    * @li InternetFamily: an address for connecting to the Internet
  311.    * @li InetFamily: alias for InternetFamily
  312.    * @li IPv6Family: an IPv6 address only
  313.    * @li IPv4Family: an IPv4 address only
  314.    * @li UnixFamily: an address for the local Unix namespace (i.e., Unix sockets)
  315.    * @li LocalFamily: alias for UnixFamily
  316.    */
  317.   enum SocketFamilies
  318.   {
  319.     UnknownFamily = 0x0001,
  320.  
  321.     UnixFamily = 0x0002,
  322.     LocalFamily = UnixFamily,
  323.  
  324.     IPv4Family = 0x0004,
  325.     IPv6Family = 0x0008,
  326.     InternetFamily = IPv4Family | IPv6Family,
  327.     InetFamily = InternetFamily,
  328.  
  329.     KnownFamily = ~UnknownFamily,
  330.     AnyFamily = KnownFamily | UnknownFamily
  331.   };
  332.  
  333.   /**
  334.    * Flags for the resolution.
  335.    *
  336.    * These flags are used for setting the resolution behaviour for this
  337.    * object:
  338.    * @li Passive: resolve to a passive socket (i.e., one that can be used for
  339.    *        binding to a local interface)
  340.    * @li CanonName: request that the canonical name for the given nodename
  341.    *        be found and recorded
  342.    * @li NoResolve: request that no external resolution be performed. The given
  343.    *        nodename and servicename will be resolved locally only.
  344.    * @li NoSrv: don't try to use SRV-based name-resolution. (deprecated)
  345.    * @li UseSrv: use SRV-based name resolution.
  346.    * @li Multiport: the port/service argument is a list of port numbers and
  347.    *        ranges. (future extension)
  348.    *
  349.    * @note SRV-based lookup and Multiport are not implemented yet.
  350.    */
  351.   enum Flags
  352.     {
  353.       Passive = 0x01,
  354.       CanonName = 0x02,
  355.       NoResolve = 0x04,
  356.       NoSrv = 0x08,
  357.       Multiport = 0x10,
  358.       UseSrv = 0x20
  359.     };
  360.  
  361.   /**
  362.    * Error codes
  363.    *
  364.    * These are the possible error values that objects of this class
  365.    * may return. See \ref errorString() for getting a string representation
  366.    * for these errors.
  367.    *
  368.    * @li AddrFamily: Address family for the given nodename is not supported.
  369.    * @li TryAgain: Temporary failure in name resolution. You should try again.
  370.    * @li NonRecoverable: Non-recoverable failure in name resolution.
  371.    * @li BadFlags: Invalid flags were given.
  372.    * @li Memory: Memory allocation failure.
  373.    * @li NoName: The specified name or service doesn't exist.
  374.    * @li UnsupportedFamily: The requested socket family is not supported.
  375.    * @li UnsupportedService: The requested service is not supported for this
  376.    *        socket type (i.e., a datagram service in a streaming socket).
  377.    * @li UnsupportedSocketType: The requested socket type is not supported.
  378.    * @li UnknownError: An unknown, unexpected error occurred.
  379.    * @li SystemError: A system error occurred. See @ref systemError.
  380.    * @li Canceled: This request was cancelled by the user.
  381.    */
  382.   enum ErrorCodes
  383.     {
  384.       // note: if you change this enum, take a look at KResolver::errorString
  385.       NoError = 0,
  386.       AddrFamily = -1,
  387.       TryAgain = -2,
  388.       NonRecoverable = -3,
  389.       BadFlags = -4,
  390.       Memory = -5,
  391.       NoName = -6,
  392.       UnsupportedFamily = -7,
  393.       UnsupportedService = -8,
  394.       UnsupportedSocketType = -9,
  395.       UnknownError = -10,
  396.       SystemError = -11,
  397.       Canceled = -100
  398.     };
  399.  
  400.   /**
  401.    * Status codes.
  402.    *
  403.    * These are the possible status for a Resolver object. A value
  404.    * greater than zero indicates normal behaviour, while negative
  405.    * values either indicate failure or error.
  406.    *
  407.    * @li Idle: resolution has not yet been started.
  408.    * @li Queued: resolution is queued but not yet in progress.
  409.    * @li InProgress: resolution is in progress.
  410.    * @li PostProcessing: resolution is in progress.
  411.    * @li Success: resolution is done; you can retrieve the results.
  412.    * @li Canceled: request cancelled by the user.
  413.    * @li Failed: resolution is done, but failed.
  414.    *
  415.    * Note: the status Canceled and the error code Canceled are the same.
  416.    *
  417.    * Note 2: the status Queued and InProgress might not be distinguishable.
  418.    * Some implementations might not differentiate one from the other.
  419.    */
  420.   enum StatusCodes
  421.     {
  422.       Idle = 0,
  423.       Queued = 1,
  424.       InProgress = 5,
  425.       PostProcessing = 6,
  426.       Success = 10,
  427.       //Canceled = -100,    // already defined above
  428.       Failed = -101
  429.     };
  430.  
  431.   /**
  432.    * Default constructor.
  433.    *
  434.    * Creates an empty Resolver object. You should set the wanted
  435.    * names and flags using the member functions before starting
  436.    * the name resolution.
  437.    */
  438.   KResolver(QObject * = 0L, const char * = 0L);
  439.  
  440.   /**
  441.    * Constructor with host and service names.
  442.    *
  443.    * Creates a Resolver object with the given host and
  444.    * service names. Flags are initialised to 0 and any address family
  445.    * will be accepted.
  446.    *
  447.    * @param nodename    The host name we want resolved.
  448.    * @param servicename    The service name associated, like "http".
  449.    */
  450.   KResolver(const QString& nodename, const QString& servicename = QString::null,
  451.         QObject * = 0L, const char * = 0L);
  452.  
  453.   /**
  454.    * Destructor.
  455.    *
  456.    * When this object is deleted, it'll destroy all associated
  457.    * resources. If the resolution is still in progress, it will be
  458.    * cancelled and the signal will \b not be emitted.
  459.    */
  460.   virtual ~KResolver();
  461.  
  462.   /**
  463.    * Retrieve the current status of this object.
  464.    *
  465.    * @see StatusCodes for the possible status codes.
  466.    */
  467.   int status() const;
  468.  
  469.   /**
  470.    * Retrieve the error code in this object.
  471.    *
  472.    * This function will return NoError if we are not in
  473.    * an error condition. See @ref status and @ref StatusCodes to
  474.    * find out what the current status is.
  475.    *
  476.    * @see errorString for getting a textual representation of
  477.    * this error
  478.    */
  479.   int error() const;
  480.  
  481.   /**
  482.    * Retrieve the associated system error code in this object.
  483.    *
  484.    * Many resolution operations may generate an extra error code
  485.    * as given by the C errno variable. That value is stored in the
  486.    * object and can be retrieved by this function.
  487.    */
  488.   int systemError() const;
  489.  
  490.   /**
  491.    * Returns the textual representation of the error in this object.
  492.    */
  493.   inline QString errorString() const
  494.   { return errorString(error(), systemError()); }
  495.  
  496.   /**
  497.    * Returns true if this object is currently running
  498.    */
  499.   bool isRunning() const;
  500.  
  501.   /**
  502.    * The nodename to which the resolution was/is to be performed.
  503.    */
  504.   QString nodeName() const;
  505.  
  506.   /**
  507.    * The service name to which the resolution was/is to be performed.
  508.    */
  509.   QString serviceName() const;
  510.  
  511.   /**
  512.    * Sets the nodename for the resolution.
  513.    *
  514.    * Set the nodename to QString::null to unset it.
  515.    * @param nodename        The nodename to be resolved.
  516.    */
  517.   void setNodeName(const QString& nodename);
  518.  
  519.   /**
  520.    * Sets the service name to be resolved.
  521.    *
  522.    * Set it to QString::null to unset it.
  523.    * @param service        The service to be resolved.
  524.    */
  525.   void setServiceName(const QString& service);
  526.  
  527.   /**
  528.    * Sets both the host and the service names.
  529.    *
  530.    * Setting either value to QString::null will unset them.
  531.    * @param node        The nodename
  532.    * @param service        The service name
  533.    */
  534.   void setAddress(const QString& node, const QString& service);
  535.  
  536.   /**
  537.    * Retrieves the flags set for the resolution.
  538.    *
  539.    * @see Flags for an explanation on what flags are possible
  540.    */
  541.   int flags() const;
  542.  
  543.   /**
  544.    * Sets the flags.
  545.    *
  546.    * @param flags        the new flags
  547.    * @return            the old flags
  548.    * @see Flags for an explanation on the flags
  549.    */
  550.   int setFlags(int flags);
  551.  
  552.   /**
  553.    * Sets the allowed socket families.
  554.    *
  555.    * @param families        the families that we want/accept
  556.    * @see SocketFamilies for possible values
  557.    */
  558.   void setFamily(int families);
  559.  
  560.   /**
  561.    * Sets the socket type we want.
  562.    *
  563.    * The values for the @p type parameter are the SOCK_*
  564.    * constants, defined in <sys/socket.h>. The most common
  565.    * values are:
  566.    *  @li SOCK_STREAM        streaming socket (= reliable, sequenced,
  567.    *                connection-based)
  568.    *  @li SOCK_DGRAM        datagram socket (= unreliable, connectionless)
  569.    *  @li SOCK_RAW        raw socket, with direct access to the
  570.    *                container protocol (such as IP)
  571.    *
  572.    * These three are the only values to which it is guaranteed that
  573.    * resolution will work. Some systems may define other constants (such as
  574.    * SOCK_RDM for reliable datagrams), but support is implementation-defined.
  575.    * 
  576.    * @param type        the wanted socket type (SOCK_* constants). Set
  577.    *                0 to use the default.
  578.    */
  579.   void setSocketType(int type);
  580.  
  581.   /**
  582.    * Sets the protocol we want.
  583.    *
  584.    * Protocols are dependant on the selected address family, so you should know
  585.    * what you are doing if you use this function. Besides, protocols generally
  586.    * are either stream-based or datagram-based, so the value of the socket
  587.    * type is also important. The resolution will fail if these values don't match.
  588.    *
  589.    * When using an Internet socket, the values for the protocol are the
  590.    * IPPROTO_* constants, defined in <netinet/in.h>.
  591.    *
  592.    * You may choose to set the protocol either by its number or by its name, or
  593.    * by both. If you set:
  594.    * @li the number and the name: both values will be stored internally; you
  595.    *        may set the name to an empty value, if wanted
  596.    * @li the number only (name = NULL): the name will be searched in the 
  597.    *        protocols database
  598.    * @li the name only (number = 0): the number will be searched in the
  599.    *        database
  600.    * @li neither name nor number: reset to default behaviour
  601.    *
  602.    * @param protonum        the protocol number we want
  603.    * @param name        the protocol name
  604.    */
  605.   void setProtocol(int protonum, const char *name = 0L);
  606.  
  607.   /**
  608.    * Starts the name resolution asynchronously.
  609.    *
  610.    * This function will queue this object for resolution
  611.    * and will return immediately. The status upon exit will either be
  612.    * Queued or InProgress or Failed.
  613.    *
  614.    * This function does nothing if the object is already queued. But if
  615.    * it had already succeeded or failed, this function will re-start it.
  616.    *
  617.    * Note: if both the nodename and the servicename are unset, this function
  618.    * will not queue, but will set a success state and emit the signal. Also
  619.    * note that in this case and maybe others, the signal @ref finished might
  620.    * be emitted before this function returns.
  621.    *
  622.    * @return true if this request was successfully queued for asynchronous
  623.    *        resolution
  624.    */
  625.   bool start();
  626.  
  627.   /**
  628.    * Waits for a request to finish resolving.
  629.    *
  630.    * This function will wait on a running request for its termination. The
  631.    * status upon exit will either be Success or Failed or Canceled.
  632.    *
  633.    * This function may be called from any thread, even one that is not the
  634.    * GUI thread or the one that started the resolution process. But note this
  635.    * function is not thread-safe nor reentrant: i.e., only one thread can be
  636.    * waiting on one given object.
  637.    *
  638.    * Also note that this function ensures that the @ref finished signal is
  639.    * emitted before it returns. That means that, as a side-effect, whenever
  640.    * wait() is called, the signal is emitted on the thread calling wait().
  641.    *
  642.    * @param msec        the time to wait, in milliseconds or 0 to
  643.    *                wait forever
  644.    * @return true if the resolution has finished processing, even when it
  645.    *         failed or was canceled. False means the wait timed out and
  646.    *         the resolution is still running.
  647.    */
  648.   bool wait(int msec = 0);
  649.  
  650.   /**
  651.    * Cancels a running request
  652.    *
  653.    * This function will cancel a running request. If the request is not
  654.    * currently running or queued, this function does nothing.
  655.    *
  656.    * Note: if you tell the signal to be emitted, be aware that it might
  657.    * or might not be emitted before this function returns.
  658.    *
  659.    * @param emitSignal    whether to emit the @ref finished signal or not
  660.    */
  661.   void cancel(bool emitSignal = true);
  662.  
  663.   /**
  664.    * Retrieves the results of this resolution
  665.    *
  666.    * Use this function to retrieve the results of the resolution. If no
  667.    * data was resolved (yet) or if we failed, this function will return
  668.    * an empty object.
  669.    *
  670.    * @return the resolved data
  671.    * @see status for information on finding out if the resolution was successful
  672.    */
  673.   KResolverResults results() const;
  674.  
  675.   /**
  676.    * Handles events. Reimplemented from QObject.
  677.    *
  678.    * This function handles the events generated by the manager indicating that
  679.    * this object has finished processing.
  680.    *
  681.    * Do not post events to this object.
  682.    */
  683.   virtual bool event(QEvent*);
  684.  
  685. signals:
  686.   // signals
  687.  
  688.   /**
  689.    * This signal is emitted whenever the resolution is finished, one
  690.    * way or another (success or failure). The @p results parameter
  691.    * will contain the resolved data.
  692.    *
  693.    * Note: if you are doing multiple resolutions, you can use the 
  694.    * QObject::sender() function to distinguish one Resolver object from
  695.    * another.
  696.    *
  697.    * @param results        the resolved data; might be empty if the resolution
  698.    *            failed
  699.    * @see results for information on what the results are
  700.    *
  701.    * @note This signal is @b always delivered in the GUI event thread, even for
  702.    *       resolutions that were started in secondary threads.
  703.    */
  704.   void finished(KResolverResults results);
  705.  
  706. private:
  707.   void emitFinished();
  708.  
  709. public:
  710.   // Static functions
  711.  
  712.   /**
  713.    * Returns the string representation of this error code.
  714.    *
  715.    * @param errorcode    the error code. See @ref ErrorCodes.
  716.    * @param syserror    the system error code associated.
  717.    * @return        the string representation. This is already
  718.    *            i18n'ed.
  719.    */
  720.   static QString errorString(int errorcode, int syserror = 0);
  721.  
  722.   /**
  723.    * Resolve the nodename and service name synchronously
  724.    *
  725.    * This static function is provided as convenience for simplifying
  726.    * name resolution. It resolves the given host and service names synchronously
  727.    * and returns the results it found. It is equivalent to the following code:
  728.    *
  729.    * \code
  730.    *   KResolver qres(host, service);
  731.    *   qres.setFlags(flags);
  732.    *   qres.setFamily(families)
  733.    *   qres.start();
  734.    *   qres.wait();
  735.    *   return qres.results();
  736.    * \endcode
  737.    *
  738.    * @param host        the nodename to resolve
  739.    * @param service        the service to resolve
  740.    * @param flags        flags to be used
  741.    * @param families        the families to be searched
  742.    * @return a KResolverResults object containing the results
  743.    * @see KResolverResults for information on how to obtain the error code
  744.    */
  745.   static KResolverResults resolve(const QString& host, const QString& service,
  746.                  int flags = 0, int families = KResolver::InternetFamily);
  747.  
  748.   /**
  749.    * Start an asynchronous name resolution
  750.    *
  751.    * This function is provided as a convenience to simplify the resolution
  752.    * process. It creates an internal KResolver object, connects the
  753.    * @ref finished signal to the given slot and starts the resolution
  754.    * asynchronously. It is more or less equivalent to the following code:
  755.    *
  756.    * \b Note: this function may trigger the signal before it returns, so
  757.    * your code must be prepared for this situation.
  758.    *
  759.    * \code
  760.    *   KResolver* qres = new KResolver(host, service);
  761.    *   QObject::connect(qres, SIGNAL(finished(KResolverResults)),
  762.    *              userObj, userSlot);
  763.    *   qres->setFlags(flags);
  764.    *   qres->setFamily(families);
  765.    *   return qres->start();
  766.    * \endcode
  767.    *
  768.    * You should use it like this in your code:
  769.    * \code
  770.    *   KResolver::resolveAsync(myObj, SLOT(mySlot(KResolverResults)), host, service);
  771.    * \endcode
  772.    *
  773.    * @param userObj        the object whose slot @p userSlot we will connect
  774.    * @param userSlot        the slot to which we'll connect
  775.    * @param host        the nodename to resolve
  776.    * @param service        the service to resolve
  777.    * @param flags        flags to be used
  778.    * @param families        families to be searcheed
  779.    * @return true if the queueing was successful, false if not
  780.    * @see KResolverResults for information on how to obtain the error code
  781.    */
  782.   static bool resolveAsync(QObject* userObj, const char *userSlot,
  783.                const QString& host, const QString& service,
  784.                int flags = 0, int families = KResolver::InternetFamily);
  785.  
  786.   /**
  787.    * Returns the domain name in an ASCII Compatible Encoding form, suitable
  788.    * for DNS lookups. This is the base for International Domain Name support
  789.    * over the Internet.
  790.    *
  791.    * Note this function may fail, in which case it'll return a null 
  792.    * QCString. Reasons for failure include use of unknown code
  793.    * points (Unicode characters).
  794.    *
  795.    * Note that the encoding is illegible and, thus, should not be presented
  796.    * to the user, except if requested.
  797.    *
  798.    * @param unicodeDomain    the domain name to be encoded
  799.    * @return the ACE-encoded suitable for DNS queries if successful, a null
  800.    *         QCString if failure.
  801.    */
  802.   static QCString domainToAscii(const QString& unicodeDomain);
  803.  
  804.   /**
  805.    * Does the inverse of @ref domainToAscii and return an Unicode domain
  806.    * name from the given ACE-encoded domain.
  807.    *
  808.    * This function may fail if the given domain cannot be successfully
  809.    * converted back to Unicode. Reasons for failure include a malformed
  810.    * domain name or good ones whose reencoding back to ACE don't match
  811.    * the form given here (e.g., ACE-encoding of an already
  812.    * ASCII-compatible domain).
  813.    *
  814.    * It is, however, guaranteed that domains returned
  815.    * by @ref domainToAscii will work.
  816.    *
  817.    * @param asciiDomain    the ACE-encoded domain name to be decoded
  818.    * @return the Unicode representation of the given domain name
  819.    * if successful, the original string if not
  820.    * @note ACE = ASCII-Compatible Encoding, i.e., 7-bit
  821.    */
  822.   static QString domainToUnicode(const QCString& asciiDomain);
  823.  
  824.   /**
  825.    * The same as above, but taking a QString argument.
  826.    *
  827.    * @param asciiDomain    the ACE-encoded domain name to be decoded
  828.    * @return the Unicode representation of the given domain name
  829.    * if successful, QString::null if not.
  830.    */
  831.   static QString domainToUnicode(const QString& asciiDomain);
  832.  
  833.   /**
  834.    * Normalise a domain name.
  835.    *
  836.    * In order to prevent simple mistakes in International Domain
  837.    * Names (IDN), it has been decided that certain code points
  838.    * (characters in Unicode) would be instead converted to others.
  839.    * This includes turning them all to lower case, as well certain
  840.    * other specific operations, as specified in the documents.
  841.    *
  842.    * For instance, the German '├ƒ' will be changed into 'ss', while
  843.    * the micro symbol '┬╡' will be changed to the Greek mu '╬╝'.
  844.    *
  845.    * Two equivalent domains have the same normalised form. And the
  846.    * normalised form of a normalised domain is itself (i.e., if 
  847.    * d is normalised, the following is true: d == normalizeDomain(d) )
  848.    *
  849.    * This operation is equivalent to encoding and the decoding a Unicode
  850.    * hostname.
  851.    *
  852.    * @param domain        a domain to be normalised
  853.    * @return the normalised domain, or QString::null if the domain is
  854.    * invalid.
  855.    */
  856.   static QString normalizeDomain(const QString& domain);
  857.  
  858.   /**
  859.    * Resolves a protocol number to its names
  860.    *
  861.    * Note: the returned QStrList operates on deep-copies.
  862.    *
  863.    * @param protonum    the protocol number to be looked for
  864.    * @return all the protocol names in a list. The first is the "proper"
  865.    *        name.
  866.    */
  867.   static QStrList protocolName(int protonum);
  868.  
  869.   /**
  870.    * Finds all aliases for a given protocol name
  871.    *
  872.    * @param protoname    the protocol name to be looked for
  873.    * @return all the protocol names in a list. The first is the "proper"
  874.    *        name.
  875.    */
  876.   static QStrList protocolName(const char *protoname);
  877.  
  878.   /**
  879.    * Resolves a protocol name to its number
  880.    *
  881.    * @param protoname    the protocol name to be looked for
  882.    * @return the protocol number or -1 if we couldn't locate it
  883.    */
  884.   static int protocolNumber(const char *protoname);
  885.  
  886.   /**
  887.    * Resolves a service name to its port number
  888.    *
  889.    * @param servname        the service name to be looked for
  890.    * @param protoname        the protocol it is associated with
  891.    * @return the port number in host byte-order or -1 in case of error
  892.    */
  893.   static int servicePort(const char *servname, const char *protoname);
  894.  
  895.   /**
  896.    * Finds all the aliases for a given service name
  897.    *
  898.    * Note: the returned QStrList operates on deep-copies.
  899.    *
  900.    * @param servname        the service alias to be looked for
  901.    * @param protoname        the protocol it is associated with
  902.    * @return all the service names in a list. The first is the "proper"
  903.    *        name.
  904.    */
  905.   static QStrList serviceName(const char *servname, const char *protoname);
  906.  
  907.   /**
  908.    * Resolves a port number to its names
  909.    *
  910.    * Note: the returned QStrList operates on deep copies.
  911.    *
  912.    * @param port        the port number, in host byte-order
  913.    * @param protoname        the protocol it is associated with
  914.    * @return all the service names in a list. The first is the "proper"
  915.    *        name.
  916.    */
  917.   static QStrList serviceName(int port, const char *protoname);
  918.  
  919.   /**
  920.    * Returns this machine's local hostname.
  921.    *
  922.    * @return this machine's local hostname
  923.    * @since 3.5
  924.    */
  925.   static QString localHostName();
  926.  
  927. protected:
  928.  
  929.   /**
  930.    * Sets the error codes
  931.    */
  932.   void setError(int errorcode, int systemerror = 0);
  933.  
  934.   virtual void virtual_hook( int id, void* data );
  935. private:
  936.   KResolverPrivate* d;
  937.   friend class KResolverResults;
  938.   friend class ::KNetwork::Internal::KResolverManager;
  939.   
  940.   static QStringList *idnDomains;
  941. };
  942.  
  943. }                // namespace KNetwork
  944.  
  945. #endif
  946.